<html>
<head>
<title>README</title>
</head>
<body>

<h3>README - <i>Custom Keymatch OneBox</i></h3>

<p>
The <i>Keymatch OneBox</i> is a Java Servlet that mimics the built-in Keymatch functionality of the Google Search Appliance. If you've outgrown built-in Keymatch, then you can take this OneBox and configure it to your specific needs.
</p>
<p>
This readme describes the simple steps needed to build and install this OneBox.  

This package provides both a basic matcher that compiles under Java 1.4, and also a
more powerful matcher that runs order(s) of magnitude faster (requires Java 1.5).
</p>

<h3>System Requirements</h3>
The following are required to build and run the Keymatch OneBox provider:
<ul>
<li>The <a href="http://code.google.com/p/onebox-servlet-starter-kit/">OneBox Servlet Starter Kit</a> project download</li>
<li>A J2EE application server supporting servlets and JRE 1.4 or later, where you can deploy your OneBox</li>
<li>JDK 1.4 or later, to build the Keymatch servlet and WAR file</li>
<li><a href="http://ant.apache.org/">Ant</a> version 1.6.2 or later, to run the build script</li>
</ul>

<h3>Contents</h3>
<table>
<tr>
<td>
<ul>
<li><code>readme.html</code></li>
<li><code>keymatch.xml</code></li>
<li><code>Keymatch.java</code></li>
<li><code>keymatches</code></li>
<li><code>TrieKeymatch.java</code></li>
<li><code>trieMatch/</code></li>
</ul>
</td>
<td>&nbsp;&nbsp;&nbsp;</td>
<td valign=top>
<table cellspacing=0 cellpadding=0>
<tr><td> -- this file</td></tr>
<tr><td> -- module definition file</td></tr>
<tr><td> -- provider servlet source code</td></tr>
<tr><td> -- sample input file</td></tr>
<tr><td> -- trie-based servlet plugin (optional)</td></tr>
<tr><td> -- trie-based servlet source code (optional)</td></tr>

</table>
</td>
</tr>
</table>


<h3>Quick Build and Install</h3>
(For detailed instructions, or to skip the trie-based matcher, skip down to <i>Detailed Build and Install</i>)
<ol>
<li>download <a href="http://code.google.com/enterprise/download/onebox_servlet_starter_kit.zip">OneBox Servlet Starter Kit</a></li>
<li>download the <a href="http://custom-keymatch-onebox.googlecode.com/svn/trunk/downloads/custom-keymatch-onebox.zip">Custom-Keymatch-Onebox Kit</a> (full source code)</li>
<li>mkdir buildDir</li>
<li>cd buildDir</li>
<li>unzip ../onebox_servlet_starter_kit.zip</li>
<li>cd onebox_servlet_starter_kit</li>
<li>cd src</li>
<li>unzip ../../../custom-keymatch-onebox.zip</li>
<li>cp trieMatch/web.xml ..</li>
<li>cd ..</li>
<li>ant</li>
<li>echo deploy to your web server</li>
<li>echo run tests</li>
<li>cd src/trieMatch</li>
<li>echo build and test standalone test</li>
<li>ant jar</li>
<li>ant bench</li>
<li>(optional) download <a href="http://custom-keymatch-onebox.googlecode.com/svn/trunk/downloads/sampleData.zip">more test data</a>, unpack into the subdirectory src/trieMatch (overwriting src/trieMatch/sampleData), and re-issue the 'ant bench' command</li>
</ol>

<h3>Detailed Build and Install</h3>
To get up and running with the Keymatch OneBox module just follow these simple steps:
<ol>
<li>Download either the <a href="http://custom-keymatch-onebox.googlecode.com/svn/tags/release_1.0/downloads/custom-keymatch-onebox.zip">baseline Custom-Keymatch-Onebox Kit</a> baseline project distribution, or <br>
download the <a href="http://custom-keymatch-onebox.googlecode.com/svn/trunk/downloads/custom-keymatch-onebox.zip">complete Keymatch Onebox Kit</a> distribution, including trie-based matching and benchmark programs</li>
<li>Expand the distributions and modify the starter kit as follows:
	<ul>
	<li>Copy <code>Keymatch.java</code> from the keymatch distribution into the <code>onebox_servlet_starter_kit/src/</code> subdirectory</li>
    <li>Modify <code>onebox_servlet_starter_kit/web.xml</code> by adding the following just after the <i>&lt;description&gt;</i> element:<br/>
	(be sure to correctly set the <code>keymatches</code> file location and correctly point to your J2EE application server)
	<pre style="color: #1849b5">    &lt;servlet&gt; <br>        &lt;init-param&gt; <br>            &lt;param-name&gt;keymatch_file&lt;/param-name&gt; <br>            &lt;param-value&gt;<u><em>keymatches</em></u>&lt;/param-value&gt; <br>        &lt;/init-param&gt; <br>        &lt;init-param&gt; <br>            &lt;param-name&gt;url_prefix&lt;/param-name&gt; <br>            &lt;param-value&gt;<u>http://<em>localhost:8080</em>/onebox/Keymatch?</u>&lt;/param-value&gt; <br>        &lt;/init-param&gt; <br>        &lt;load-on-startup&gt;1&lt;/load-on-startup&gt; <br>        &lt;servlet-name&gt;Keymatch&lt;/servlet-name&gt; <br>        &lt;servlet-class&gt;Keymatch&lt;/servlet-class&gt; <br>    &lt;/servlet&gt; <br> <br>    &lt;servlet-mapping&gt; <br>        &lt;servlet-name&gt;Keymatch&lt;/servlet-name&gt; <br>        &lt;url-pattern&gt;/Keymatch&lt;/url-pattern&gt; <br>    &lt;/servlet-mapping&gt; <br>	</pre>
	</li></ul>
<li>Optionally, copy the trie-based matcher into the <code>onebox_servlet_starter_kit/src/</code> subdirectory. This code requires JDK 1.5 or later.
    <ul>
    <li>Copy both <code>TrieKeymatch.java</code> and the subdirectory <code>trieMatch/</code> into <code>onebox_servlet_starter_key_/src/</code></li>
	<li>Modify <code>onebox_servlet_starter_kit/web.xml</code> to use <code>TrieKeymatch</code> instead of <code>Keymatch</code><br><pre style="color: #1849b5">    &lt;servlet&gt; <br>        ... <br>        &lt;init-param&gt; <br>            &lt;param-name&gt;<b style="color: #103c94">SearchFlavor</b>&lt;/param-name&gt; <br>            &lt;param-value&gt;<b style="color: #103c94">all</b>&lt;/param-value&gt; <i> &lt;!-- longest, top, all, exp --&gt; </i> <br>        &lt;/init-param&gt; <br>        &lt;servlet-name&gt;Keymatch&lt;/servlet-name&gt; <br>        &lt;servlet-class&gt;<u><i><b style="color: rgb(16, 60, 148);">TrieKeymatch</b></i></u>&lt;/servlet-class&gt; <br>    &lt;/servlet&gt;</pre>
	</li>
	<li>The TrieKeymatch is configurable to find <i>all</i>, <i>longest</i>, <i>top</i> or <i>prefix</i> matches.</li>
	<li>Duplicate URL matches are combined by the aggregation class specified in the <code>aggregatorName</code> servlet parameter</li>
	<li>See <i>Customizing</i> (below) for more information</li><br>
	</ul>
</li>
<li>Rebuild <code>onebox_servlet_starter_kit/onebox.war</code> using the given <code>onebox_servlet_starter_kit/build.xml</code> Ant script.</li>
<li>Deploy <code>onebox_servlet_starter_kit/onebox.war</code> to your J2EE application server.  See your application server documentation on how to deploy a WAR.</li>
<li>Modify the <i>&lt;providerURL&gt;</i> element of the <code>keymatch.xml</code> module definition file to point to your J2EE application server.</li>
<li>Install the <code>keymatch.xml</code> module definition file into your Google Search Appliance.  See the <a href="https://support.google.com/enterprise/doc/gsa/4x/help/serve_onebox.html">documentation</a> on how to install the OneBox module.</li>
<li>You should now be able to run queries on the keywords in <a href="keymatches"><code>keymatches</code></a> and see Keymatches in your search results.</li>
</ol>

<h3>Customizing</h3>

Modify the <code>keymatches</code> file to alter the keywords for which your OneBox shows Keymatches.  The format of the file is one match per line, with each line taking the form of <i>keyword,matchtype,URL,displaytitle</i>.  Possible <i>matchtype</i> values include ExactMatch, KeywordMatch, and PhraseMatch.  For changes to this file to take effect, you'll need to reload(/restart/redeploy) the web application in your J2EE application server.

Modify the <code>Keymatch.java</code> Java Servlet to fundamentally change the behavior of the Keymatch OneBox. In this case the <code>onebox.war</code> file can then be rebuilt and redeployed to your application server.

The web.xml accepts search customizations under the TrieKeymatcher<br><pre style="color: #1849b5">	    &lt;servlet&gt;<br>		&lt;init-param&gt;<br>			&lt;param-name&gt;keymatch_file&lt;/param-name&gt;<br>			&lt;param-value&gt;/tmp/keymatches&lt;/param-value&gt;<br>		&lt;/init-param&gt;<br>		&lt;init-param&gt;<br>			&lt;param-name&gt;url_prefix&lt;/param-name&gt;<br>			&lt;param-value&gt;http://<em>localhost</em>:8080/onebox/Keymatch?&lt;/param-value&gt;<br>		&lt;/init-param&gt;<br>	<br>		&lt;load-on-startup&gt;1&lt;/load-on-startup&gt;<br>		&lt;servlet-name&gt;Keymatch&lt;/servlet-name&gt;<br>		&lt;!-- &lt;servlet-class&gt;Keymatch&lt;/servlet-class&gt; --&gt;<br>		&lt;servlet-class&gt;<u><b><u><b style="color: rgb(16, 60, 148);">TrieKeymatch</b></u></b></u>&lt;/servlet-class&gt;<br>		<br>		 &lt;!-- optional config when servelet-class is trieMatch.Keymatch --&gt;<br>		&lt;init-param&gt;<br>			&lt;param-name&gt;<b><b style="color: rgb(16, 60, 148);">SearchFlavor</b></b>&lt;/param-name&gt;<br>			&lt;!-- longest, top, all, exp --&gt;<br>			&lt;param-value&gt;<em><em><u><b style="color: rgb(16, 60, 148);">all</b></u></em></em>&lt;/param-value&gt;<br>		&lt;/init-param&gt;<br>		&lt;init-param&gt;<br>			&lt;param-name&gt;<b style="color: rgb(16, 60, 148);">AggregatorName</b>&lt;/param-name&gt;<br>			&lt;!-- AggregateConstant, AggregateMAX, AggregateMAXacc, AggregateSUM, AggregateSUMacc --&gt;<br>			&lt;param-value&gt;<u><b style="color: rgb(16, 60, 148);">AggregateSUM</b></u><em></em>&lt;/param-value&gt;<br>		&lt;/init-param&gt;<br>		&lt;init-param&gt;<br>			&lt;param-name&gt;<b style="color: rgb(16, 60, 148);">AggregatorParm</b>&lt;/param-name&gt;<br>			&lt;!-- Optional parameter, gives constant to add on each aggregation step. --&gt;<br>			&lt;!-- The empty value will invoke the zero-argument constructor for the aggregator. --&gt;<br>			&lt;!-- The non-empty value will invoke the one-argument constructor. All known implementations<br>			       will then execute an Integer.parseInt(arg0) on the argument passed in.  --&gt;<br>			&lt;param-value&gt;&lt;/param-value&gt;<br>		&lt;/init-param&gt;<br>		<br>	    &lt;/servlet&gt;</pre>
<font color="#ff0000"><font color="#000000"><br><strong>Notes</strong>: If </font></font><font><font><font color="#ff0000"><font color="#000000"><u>AggregatorName</u> is </font></font></font></font><font color="#ff0000"><font color="#000000">not specified in the web.xml file, the default value <u>AggregateSUM</u> will be used. The default value of <u>AggregatePARM</u> is empty.</font><em> The servlet will not start with an invalid aggregator.</em> </font><br><br>

The <i>&lt;resultsTemplate&gt;</i> element of the <code>keymatch.xml</code> file includes the XSL code that defines what your OneBox results will look like to the end-user.  The given XSL provides a display that mimics the Google Search Appliance built-in Keymatch.  See the <a href="http://code.google.com/enterprise/documentation/oneboxguide.html#providerresultsschema">XML results schema</a> to view the data elements you have to work with when customizing the XSL.

&nbsp;

</body>
</html>
